package be.nepherte.movmanager.client.services;

import java.util.List;

import be.nepherte.movmanager.client.exceptions.MovieAlreadyExistsException;
import be.nepherte.movmanager.client.exceptions.MovieNotInCollectionException;
import be.nepherte.movmanager.client.exceptions.NotLoggedInException;
import be.nepherte.movmanager.domain.Movie;
import be.nepherte.movmanager.domain.UserInfo;
import be.nepherte.movmanager.server.MovieServiceImpl;

import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * <p>
 * This class is the client side stub for movie related services. The actual
 * implementation exists on the server side in {@link MovieServiceImpl}. Apart
 * from a server side implementation, a client side asynchronous version,
 * {@link MovieServiceAsync}, is required as well. The used communication
 * protocol is Google's implementation of rpc.
 * </p>
 * 
 * <p>
 * Copyright © 2010 Bart Verhoeven
 * </p>
 * 
 * <p>
 * This file is part of MovManager.
 * </p>
 * 
 * <p>
 * MovManager is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later
 * version.
 * </p>
 * 
 * <p>
 * MovManager is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 * </p>
 * 
 * <p>
 * You should have received a copy of the GNU General Public License along with
 * MovManager. If not, see http://www.gnu.org/licenses/.
 * </p>
 * 
 * @author 	Bart Verhoeven
 * @version 0.1
 */
@RemoteServiceRelativePath("movieService")
public interface MovieService extends RemoteService {

	/**
	 * Stores a new movie on the server side in a persistent database holding
	 * the user's movie collection.
	 * 
	 * @param	movie
	 *          the movie to be stored
	 * @param	userInfo
	 *          information about the user this movie belongs to
	 * @throws	MovieAlreadyExistsException
	 *          the movie already exists in the user's movie collection
	 * @throws	NotLoggedInException
	 *          the user is not logged in
	 */
	public Movie storeMovie(Movie movie, UserInfo userInfo) throws MovieAlreadyExistsException, NotLoggedInException;
	
	/**
	 * Stores an existing but edited movie on the server in a persistent database. 
	 * 
	 * @param	movie
	 * 			the edited move to be stored
	 * @param	userInfo
	 * 			information about the user this movie belongs to
	 * @throws	NotLoggedInException
	 * 			the user is not logged in
	 */
	public void editMovie(Movie movie, UserInfo userInfo) throws MovieNotInCollectionException, NotLoggedInException;

	/**
	 * Retrieves all the movies in the user's movie collection.
	 * 
	 * @param 	userInfo
	 *          information about the user this movie belongs to
	 * @return	the list with all the movies in the user's movie collection, empty list
	 * 			if the user does not have any movies or the user does not exist.
	 * @throws	NotLoggedInException
	 * 			the user is not logged in   
	 */
	public List<Movie> getMovies(UserInfo userInfo) throws NotLoggedInException;
}
